home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3x / udmalib.z / udmalib
Encoding:
Text File  |  1998-10-20  |  9.5 KB  |  133 lines
  1.  
  2.  
  3.  
  4. uuuuddddmmmmaaaalllliiiibbbb((((3333XXXX))))                                                        uuuuddddmmmmaaaalllliiiibbbb((((3333XXXX))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _uuuu_dddd_mmmm_aaaa_llll_iiii_bbbb: _dddd_mmmm_aaaa______oooo_pppp_eeee_nnnn, _dddd_mmmm_aaaa______cccc_llll_oooo_ssss_eeee, _dddd_mmmm_aaaa______aaaa_llll_llll_oooo_cccc_bbbb_uuuu_ffff, _dddd_mmmm_aaaa______ffff_rrrr_eeee_eeee_bbbb_uuuu_ffff, _dddd_mmmm_aaaa______mmmm_kkkk_pppp_aaaa_rrrr_mmmm_ssss,
  10.      _dddd_mmmm_aaaa______ffff_rrrr_eeee_eeee_pppp_aaaa_rrrr_mmmm_ssss, _dddd_mmmm_aaaa______ssss_tttt_aaaa_rrrr_tttt - user-level access to DMA hardware
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_uuuu_dddd_mmmm_aaaa_llll_iiii_bbbb_...._hhhh_>>>>
  14.  
  15.      _uuuu_dddd_mmmm_aaaa_iiii_dddd______tttt _****_dddd_mmmm_aaaa______oooo_pppp_eeee_nnnn _((((_iiii_nnnn_tttt _bbbb_uuuu_ssss_,,,, _iiii_nnnn_tttt _aaaa_dddd_aaaa_pppp_))))_;;;;
  16.      _iiii_nnnn_tttt _dddd_mmmm_aaaa______cccc_llll_oooo_ssss_eeee _((((_dddd_mmmm_aaaa_iiii_dddd______tttt _****_dddd_pppp_))))_;;;;
  17.      _vvvv_oooo_iiii_dddd _****_dddd_mmmm_aaaa______aaaa_llll_llll_oooo_cccc_bbbb_uuuu_ffff _((((_uuuu_dddd_mmmm_aaaa_iiii_dddd______tttt _****_dddd_pppp_,,,, _iiii_nnnn_tttt _ssss_iiii_zzzz_eeee_))))_;;;;
  18.      _iiii_nnnn_tttt _dddd_mmmm_aaaa______ffff_rrrr_eeee_eeee_bbbb_uuuu_ffff _((((_uuuu_dddd_mmmm_aaaa_iiii_dddd______tttt _****_dddd_pppp_,,,, _vvvv_oooo_iiii_dddd _****_bbbb_pppp_))))_;;;;
  19.      _uuuu_dddd_mmmm_aaaa_pppp_rrrr_mmmm______tttt _****_dddd_mmmm_aaaa______mmmm_kkkk_pppp_aaaa_rrrr_mmmm_ssss _((((_uuuu_dddd_mmmm_aaaa_iiii_dddd______tttt _****_dddd_pppp_,,,, _vvvv_oooo_iiii_dddd _****_dddd_iiii_nnnn_ffff_oooo_,,,, _vvvv_oooo_iiii_dddd _****_iiii_oooo_bbbb_uuuu_ffff_,,,, _iiii_nnnn_tttt _ssss_iiii_zzzz_eeee_))))_;;;;
  20.      _iiii_nnnn_tttt _dddd_mmmm_aaaa______ffff_rrrr_eeee_eeee_pppp_aaaa_rrrr_mmmm_ssss _((((_uuuu_dddd_mmmm_aaaa_iiii_dddd______tttt _****_dddd_pppp_,,,, _uuuu_dddd_mmmm_aaaa_pppp_rrrr_mmmm______tttt _****_dddd_pppp_aaaa_rrrr_mmmm_ssss_))))_;;;;
  21.      _iiii_nnnn_tttt _dddd_mmmm_aaaa______ssss_tttt_aaaa_rrrr_tttt _((((_uuuu_dddd_mmmm_aaaa_iiii_dddd______tttt _****_dddd_pppp_,,,, _vvvv_oooo_iiii_dddd _****_bbbb_uuuu_ssss_aaaa_dddd_dddd_rrrr_,,,, _uuuu_dddd_mmmm_aaaa_pppp_rrrr_mmmm______tttt _****_dddd_pppp_aaaa_rrrr_mmmm_ssss_))))_;;;;
  22.  
  23. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.      On Challenge and Onyx systems, These routines form the basis for a
  25.      simplified interface to DMA engines, _u_s_r_d_m_a(7m) devices.  These routines
  26.      are included in a program by compiling with the -_l_u_d_m_a option.
  27.      Currently, the only supported DMA engine is for VME on the Challenge/Onyx
  28.      series.  As DMA engines become available for other hardware platforms,
  29.      support will be provided through this interface.
  30.  
  31.      An application would use the routines _d_m_a__o_p_e_n and _d_m_a__c_l_o_s_e to allocate
  32.      and deallocate access to a DMA engine.  The parameters _b_u_s and _a_d_a_p are
  33.      used to specify the type and adapter for the bus.  The type of bus is
  34.      specified with the bus definitions found in /_u_s_r/_i_n_c_l_u_d_e/_u_d_m_a_l_i_b._h.
  35.      Currently, the only supported bus is _D_M_A__V_M_E_B_U_S.  The adapter number is
  36.      used to identify which bus for the case when multiple busses of a
  37.      particular type are available.  This is equivalent to the _a_d_a_p_t_e_r= field
  38.      of the _V_E_C_T_O_R line. See _s_y_s_t_e_m(4).  _d_m_a__o_p_e_n returns an opaque handle
  39.      used by the remaining routines.  This routine may fail if a DMA engine
  40.      does not exist, is in use, or the _u_s_r_d_m_a(7m) special devices are missing.
  41.      _d_m_a__o_p_e_n returns _N_U_L_L upon error.  _d_m_a__c_l_o_s_e returns a non-zero value
  42.      upon error.  Note:  The allocated DMA buffers associated with the _d_m_a_i_d__t
  43.      must be deallocated before _d_m_a__c_l_o_s_e can be called or it will fail.
  44.  
  45.      The routines _d_m_a__a_l_l_o_c_b_u_f and _d_m_a__f_r_e_e_b_u_f are used to allocate and free
  46.      up special buffers that will be used for the DMA operations.  DMA
  47.      operations can only take place to these special buffers, since the
  48.      buffers need to be locked down and mapped.  The _s_i_z_e specifier is a byte
  49.      count.  It will be rounded up to the nearest multiple of the system page
  50.      size.  The buffer space returned from such an allocation can be divided
  51.      up into many smaller buffers, depending upon the needs of the program.
  52.      The page size of the system can be determined by calling _g_e_t_p_a_g_e_s_i_z_e(2).
  53.      _d_m_a__a_l_l_o_c_b_u_f returns _N_U_L_L upon error.  _d_m_a__f_r_e_e_b_u_f returns a non-zero
  54.      value upon error.
  55.  
  56.      The routines _d_m_a__m_k_p_a_r_m_s and _d_m_a__f_r_e_e_p_a_r_m_s are used to create and free up
  57.      bus-specific and buffer related parameters necessary to perform the DMA
  58.      operation.  The argument _d_i_n_f_o is a bus-specific data structure defined
  59.      in the header file _u_d_m_a_l_i_b._h.  For VME, this would be the _v_m_e_p_a_r_m_s__t
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. uuuuddddmmmmaaaalllliiiibbbb((((3333XXXX))))                                                        uuuuddddmmmmaaaalllliiiibbbb((((3333XXXX))))
  71.  
  72.  
  73.  
  74.      structure.  The argument _i_o_b_u_f and _s_i_z_e specifies the DMA buffer to use
  75.      and the byte count of the DMA operation.  _d_m_a__m_k_p_a_r_m_s returns a pointer
  76.      to a _u_d_m_a_p_r_m__t structure.  This is an opaque handle that defines the DMA
  77.      operation and is passed into _d_m_a__s_t_a_r_t, and _d_m_a__f_r_e_e_p_a_r_m_s.  If a buffer
  78.      is to be both read and written, a separate DMA parameter must be set up
  79.      for each direction.  Note:  _u_d_m_a_p_r_m__t pointers should not be used after
  80.      the corresponding DMA buffer has been freed up.  This may result in a
  81.      system panic.  This routine may fail if the specified buffer has been
  82.      freed or the DMA operation fails basic range checking.  This routine may
  83.      also fail if the combination of bus-specific parameters does not make
  84.      sense.  _d_m_a__m_k_p_a_r_m_s returns _N_U_L_L upon error.  _d_m_a__f_r_e_e_p_a_r_m_s returns a
  85.      non-zero value upon error.
  86.  
  87.      The last routine _d_m_a__s_t_a_r_t programs the DMA engine, starts it up, and
  88.      returns when the DMA has completed.  This routine is passed a _u_d_m_a_p_r_m__t
  89.      pointer, which specifies the buffer, size of the DMA, direction of the
  90.      DMA to or from the buffer, and bus-specific information.  This routine is
  91.      also passed the _b_u_s_a_d_d_r, the bus address of the device that is involved
  92.      in the DMA operation.  _d_m_a__s_t_a_r_t returns a non-zero value upon error.
  93.  
  94. FFFFIIIILLLLEEEESSSS
  95.      _////_dddd_eeee_vvvv_////_vvvv_mmmm_eeee_////_dddd_mmmm_aaaa_****
  96.      _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_iiii_bbbb_uuuu_dddd_mmmm_aaaa_...._ssss_oooo
  97.  
  98. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  99.      _MMMM_AAAA_KKKK_EEEE_DDDD_EEEE_VVVV(1M)
  100.      _vvvv_mmmm_eeee______dddd_mmmm_aaaa______eeee_nnnn_gggg_iiii_nnnn_eeee(3X) for Origin and Onyx2 VME option.
  101.  
  102. NNNNOOOOTTTTEEEESSSS
  103.      This library is only provided as a _D_S_O.
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.